// -*- c++ -*-
/**************************************************************/
/*  This file is licensed from, and is a trade secret of:     */
/*                                                            */
/*    Mercury Computer Systems, Incorporated                  */
/*    199 Riverneck Road                                      */
/*    Chelmsford, Massachusetts 01824-2820                    */
/*    United States of America                                */
/*    Telephone + 1 978 256-1300                              */
/*                                                            */
/*  Refer to your Software License Agreement for provisions   */
/*  on use, duplication, or disclosure.                       */
/*  US. Government users and prime contractors are also       */
/*  governed by the following Data Rights Notice:             */
/*  Use, duplication or disclosure by the US. Government is   */
/*  subject to the provisions set forth in FAR 52.227-14 for  */
/*  restricted rights or other agency data rights provisions  */
/*  on commercial software and documentation, as applicable.  */
/*                                                            */
/*  This file: (a) was developed at private expense, and no   */
/*  part was developed with government funds, (b) is a        */
/*  trade secret of Mercury Computer Systems, Inc. for the    */
/*  purposes of the Freedom of Information Act, (c) is        */
/*  "commercial computer software" subject to limited         */
/*  utilization as provided in the above noted Software       */
/*  License Agreement and (d) is in all respects data         */
/*  belonging exclusively to Mercury Computer Systems, Inc..  */
/*                                                            */
/**************************************************************/

/******************************************************************/
/* Copyright (c) 1999-2003, Mercury Computer Systems, Inc.,       */
/* Chelmsford MA.,and all third party embedded software sources.  */
/* All rights reserved under the Copyright laws of US. and        */
/* international treaties.                                        */
/*                                                                */
/* Patent Pending                                                 */
/******************************************************************/


//$COPYRIGHT_END


#ifndef SCEOSSEMAPHORE_H__
#define SCEOSSEMAPHORE_H__

#include <string>

#ifdef WIN32
#pragma warning (disable : 4290)
#endif

/*
 * Abstract:
 *
 *     A signaling mechanism between threads within the same process. A
 *     semaphore is an unsigned integer variable that can be atomically
 *     incremented (using post()) and decremented (using wait()). If the
 *     value of the integer is zero, a decrement operation will block
 *     until a different thread increments the semaphore.
 *
 *     A single instance is shared between the threads that want to
 *     synchronize.
 */

namespace SCE {
  namespace OS {

    class Semaphore {
    public:
      /*
       * Constructor: Initializes the semaphore instance.
       *
       * [in] initial: Sets the initial value of the semaphore.
       */

      Semaphore (unsigned int initial = 1)
	throw (std::string);

      ~Semaphore ()
	throw ();

      /*
       * post(): Increase the value of the semaphore.
       *
       * If any threads are blocked in wait(), one of them is awakened.
       */

      void post ()
	throw (std::string);

      /*
       * bool wait(int timeout): Decrease the value of the semaphore.
       *
       * [in] timeout: timeout parameter (in MilliSeconds)
       *  if 0, the timeout is forever
       *
       * returns false if a timeout occured; true if no timeout
       *
       * If the value of the semaphore is positive, it is decremented,
       * and the operation returns without blocking.
       *
       * If the value of the semaphore is zero, blocks until another
       * thread increases its value using the post() operation.
       */

      bool wait (int timeout=0)
	throw (std::string);

    private:
      char m_osOpaque[76];

    private:
      Semaphore (const Semaphore &);
      Semaphore & operator= (const Semaphore &);
    };

  }
}

#endif
